ATOM Documentation

┌─────────────────────────────────────────────────────────────┐
│                     Agent Execution Flow                     │
└─────────────────────────────────────────────────────────────┘

    ┌──────────────┐
    │   Task       │
    │  Request     │
    └──────┬───────┘
           │
           ▼
    ┌──────────────────────────────────────────────────────┐
    │  1. CONTEXT RESOLUTION                               │
    │  - Resolve agent configuration                        │
    │  - Load tenant context                                │
    │  - Initialize brain systems                           │
    └────────────────────┬─────────────────────────────────┘
                         │
                         ▼
    ┌──────────────────────────────────────────────────────┐
    │  2. GOVERNANCE CHECK (Pre-Execution)                 │
    │  AgentGovernanceService.canPerformAction()           │
    │  - Check maturity level                               │
    │  - Verify permissions                                 │
    │  - Validate rate limits                               │
    └────────────────────┬─────────────────────────────────┘
                         │ Allowed
                         ▼
    ┌──────────────────────────────────────────────────────┐
    │  3. MEMORY RECALL                                     │
    │  WorldModelService.recallExperiences()                │
    │  - Find similar past experiences                      │
    │  - Load relevant learnings                            │
    │  - Retrieve context patterns                          │
    └────────────────────┬─────────────────────────────────┘
                         │
                         ▼
    ┌──────────────────────────────────────────────────────┐
    │  4. COGNITIVE PROCESSING                              │
    │  CognitiveArchitecture.reason()                       │
    │  - Allocate attention resources                       │
    │  - Analyze task requirements                          │
    │  - Generate reasoning approach                        │
    │  - Select decision strategy                           │
    └────────────────────┬─────────────────────────────────┘
                         │
                         ▼
    ┌──────────────────────────────────────────────────────┐
    │  5. SKILL EXECUTION                                   │
    │  SkillExecutor.execute()                              │
    │  - Execute agent skill/tool                           │
    │  - Monitor progress                                   │
    │  - Handle errors                                      │
    └────────────────────┬─────────────────────────────────┘
                         │
                         ▼
    ┌──────────────────────────────────────────────────────┐
    │  6. CROSS-SYSTEM CORRELATION (If Needed)              │
    │  CrossSystemReasoning.query()                         │
    │  - Correlate data across integrations                 │
    │  - Enrich with external context                       │
    │  - Identify related entities                          │
    └────────────────────┬─────────────────────────────────┘
                         │
                         ▼
    ┌──────────────────────────────────────────────────────┐
    │  7. RESULT EVALUATION                                 │
    │  CognitiveArchitecture.evaluateReasoning()           │
    │  - Assess outcome quality                             │
    │  - Calculate success metrics                          │
    │  - Generate insights                                  │
    └────────────────────┬─────────────────────────────────┘
                         │
                         ▼
    ┌──────────────────────────────────────────────────────┐
    │  8. EXPERIENCE RECORDING                              │
    │  WorldModelService.recordExperience()                │
    │  LearningEngine.recordExperience()                    │
    │  - Store outcome in memory                            │
    │  - Extract learnings                                  │
    │  - Generate reflections                               │
    │  - Identify patterns                                  │
    └────────────────────┬─────────────────────────────────┘
                         │
                         ▼
    ┌──────────────────────────────────────────────────────┐
    │  9. ADAPTATION (Optional)                             │
    │  LearningEngine.generateAdaptations()                 │
    │  - Suggest behavioral changes                         │
    │  - Apply validated adaptations                        │
    │  - Update cognitive profile                           │
    └────────────────────┬─────────────────────────────────┘
                         │
                         ▼
                    ┌─────────┐
                    │ Result  │
                    └─────────┘

import { CognitiveArchitecture } from '@/lib/ai/cognitive-architecture'

const cognitive = new CognitiveArchitecture(db, llmRouter)
await cognitive.initializeAgent(tenantId, agentId)

// Perform reasoning on a complex problem
const result = await cognitive.reason(
  tenantId,
  agentId,
  {
    type: 'decision',
    description: 'Should we escalate this customer issue?',
    context: {
      customer_tier: 'enterprise',
      issue_severity: 'high',
      time_open: 48  // hours
    }
  },
  {
    available_actions: ['resolve', 'escalate', 'defer'],
    constraints: {
      max_response_time: 4000  // 4 hours SLA
    }
  }
)

console.log(result.recommendation)  // "escalate"
console.log(result.confidence)     // 0.85
console.log(result.reasoning)      // Array of reasoning steps

import { LearningAdaptationEngine } from '@/lib/ai/learning-adaptation-engine'

const learning = new LearningAdaptationEngine(db, llmRouter)

// Record a task outcome
await learning.recordExperience(tenantId, {
  id: 'exp_123',
  type: 'success',
  context: {
    tenantId,
    agentId,
    environment: 'production',
    conditions: { task_type: 'customer_support' }
  },
  inputs: {
    customer_query: 'Password reset not working',
    strategy: 'empathetic troubleshooting'
  },
  actions: [
    { type: 'authenticate', parameters: {}, timestamp: new Date() },
    { type: 'reset_password', parameters: {}, timestamp: new Date() }
  ],
  outcomes: {
    primary: 0.9,  // 90% success
    secondary: { customer_satisfaction: 0.95 },
    duration: 180,  // seconds
    quality: 0.88,
    efficiency: 0.92
  },
  feedback: {
    immediate: 0.9,
    source: 'customer_rating',
    confidence: 0.95
  },
  reflections: [
    { insight: 'Quick authentication reduced frustration', impact: 'high', generalizability: 0.8, novelty: 0.3 }
  ],
  patterns: [],
  timestamp: new Date()
})

// Generate adaptations based on learning
const adaptations = await learning.generateAdaptations(tenantId, agentId)

for (const adaptation of adaptations) {
  console.log(`Suggested: ${adaptation.description}`)
  console.log(`Expected improvement: ${adaptation.expected_impact}`)

  // Apply validated adaptations
  if (adaptation.validation_score > 0.8) {
    await learning.applyAdaptation(tenantId, adaptation)
  }
}

import { WorldModelService } from '@/lib/ai/world-model'

const worldModel = new WorldModelService(db)

// Record a new experience
await worldModel.recordExperience(tenantId, {
  agent_id: agentId,
  agent_role: 'customer_support',
  task_type: 'refund_request',
  task_description: 'Customer requested refund for defective product',
  input_summary: 'Product arrived damaged, customer upset',
  outcome: 'Approved refund with 20% bonus',
  outcome_score: 0.95,
  learnings: [
    'Approaching with empathy reduces tension',
    'Adding bonus increases customer loyalty',
    'Need to check inventory before promising replacement'
  ],
  metadata: {
    customer_tier: 'enterprise',
    refund_amount: 250,
    resolution_time: 300  // minutes
  }
})

// Recall relevant experiences for a new task
const memories = await worldModel.recallExperiences(
  tenantId,
  'customer_support',
  'Customer is angry about delivery delay',
  5  // Retrieve top 5 most relevant memories
)

console.log(`Found ${memories.length} relevant past experiences`)

for (const memory of memories) {
  console.log(`- ${memory.input_summary}`)
  console.log(`  Outcome: ${memory.outcome}`)
  console.log(`  Similarity: ${memory.similarity?.toFixed(2)}`)
  console.log(`  Learnings: ${memory.learnings.join(', ')}`)
}

import { ReasoningEngine } from '@/lib/ai/reasoning-engine'

const reasoning = new ReasoningEngine(db)

// Generate proactive insights
const interventions = await reasoning.generateInterventions(tenantId)

for (const intervention of interventions) {
  if (intervention.type === 'URGENT') {
    console.log(`🚨 ${intervention.title}`)
    console.log(`   ${intervention.description}`)
    console.log(`   Action: ${intervention.recommended_action}`)

    // Handle urgent intervention
    await notifyTeam(intervention)
  }
  else if (intervention.type === 'OPPORTUNITY') {
    console.log(`💡 ${intervention.title}`)
    console.log(`   ${intervention.description}`)
    console.log(`   Expected impact: ${intervention.expected_impact}`)

    // Queue for review
    await queueOpportunity(intervention)
  }
  else if (intervention.type === 'AUTOMATION') {
    console.log(`🤖 ${intervention.title}`)
    console.log(`   ${intervention.description}`)

    // Apply automation if safe
    if (intervention.confidence > 0.9) {
      await applyAutomation(intervention)
    }
  }
}

import { CrossSystemReasoning } from '@/lib/ai/cross-system-reasoning'

const crossSystem = new CrossSystemReasoning(tenantId)

// Query across multiple systems
const answer = await crossSystem.query(
  "What's the status of deals that mentioned 'budget' in Slack calls this week?"
)

console.log(answer.synthesis)
// "Found 3 deals in Salesforce where Slack discussions mentioned budget concerns:
//  1. Acme Corp - $50k deal stalled (budget mentioned in 3 calls)
//  2. TechStart Inc - $25k deal progressing (budget approved)
//  3. Global Industries - $100k deal at risk (budget cuts discussed)"

console.log(`Confidence: ${answer.confidence}`)
console.log(`Sources: ${answer.sources.join(', ')}`)

// Access correlated data
for (const entity of answer.correlated_entities) {
  console.log(`\nEntity: ${entity.name}`)
  console.log(`  Type: ${entity.type}`)
  console.log(`  Salesforce: ${entity.system_ids.salesforce}`)
  console.log(`  Slack: ${entity.system_ids.slack}`)
}

import { AgentGovernanceService } from '@/lib/ai/agent-governance'

const governance = new AgentGovernanceService(db)

// Check if agent can perform an action
const decision = await governance.canPerformAction(
  tenantId,
  agentId,
  'DELETE'  // Action type
)

if (!decision.allowed) {
  console.log(`❌ Action not allowed: ${decision.reason}`)
  console.log(`   Agent maturity: ${decision.agent_maturity}`)
  console.log(`   Required maturity: ${decision.required_maturity}`)

  // Request human approval if possible
  if (decision.can_request_approval) {
    const approval = await requestHumanApproval({
      agent_id: agentId,
      action: 'DELETE',
      reason: decision.reason,
      risk_level: decision.risk_level
    })

    if (approval.granted) {
      console.log('✅ Human approval received, proceeding with action')
    }
  }
  else {
    throw new Error(`Action prohibited: ${decision.reason}`)
  }
}

// Log the action for audit
await governance.logAction({
  tenant_id: tenantId,
  agent_id: agentId,
  action_type: 'DELETE',
  allowed: true,
  maturity_level: decision.agent_maturity,
  timestamp: new Date()
})

Task Start
    │
    ├─> World Model (recall similar experiences)
    │       └─> Returns: Relevant memories with similarity scores
    │
    ├─> Cognitive Architecture (use memories for reasoning)
    │       └─> Uses: Past outcomes to inform decisions
    │
    ├─> Skill Execution (perform action)
    │
    └─> Task Complete
            │
            ├─> Cognitive Architecture (evaluate outcome)
            │       └─> Returns: Quality assessment
            │
            ├─> World Model (store new experience)
            │       └─> Stores: Task, outcome, learnings
            │
            └─> Learning Engine (analyze and adapt)
                    ├─> Extract learnings
                    ├─> Generate reflections
                    ├─> Identify patterns
                    └─> Suggest adaptations

Action Requested
    │
    ├─> Agent Governance (check permissions)
    │       ├─> Allowed? ──No──> Return/Deny
    │       │       │
    │       │      Yes
    │       │       │
    │       │       ▼
    │       ├─> High Risk? ──Yes──> Request Approval
    │       │       │
    │       │      No
    │       │       │
    │       │       ▼
    │       └─> Check Rate Limits
    │               ├─> Exceeded? ──Yes──> Return/Throttle
    │               │       │
    │               │      No
    │               │       │
    │               │       ▼
    │               └─> Log Action
    │                       │
    │                       ▼
    └─> Execute Action

Cross-System Query
    │
    ├─> Parse Query
    │       └─> Extract entities, intent, scope
    │
    ├─> Route to Integrations
    │       ├─> Salesforce (deals, contacts)
    │       ├─> Slack (messages, channels)
    │       ├─> Calendar (events)
    │       ├─> Outlook (emails)
    │       └─> [Other systems]
    │
    ├─> Correlate Results
    │       ├─> Resolve entities across systems
    │       ├─> Build relationship graph
    │       └─> Enrich with context
    │
    └─> Synthesize Answer
            ├─> Generate cohesive response
            ├─> Cite sources
            └─> Provide confidence score

// 1. Resolve context
const context = await new AgentContextResolver(db).resolve(tenantId, agentId, taskId)

// 2. Recall relevant experiences
const worldModel = new WorldModelService(db)
const memories = await worldModel.recallExperiences(tenantId, agentRole, taskDescription, 5)

// 3. Check governance
const governance = new AgentGovernanceService(db)
const decision = await governance.canPerformAction(tenantId, agentId, actionType)

if (!decision.allowed) {
  throw new Error(`Action not allowed: ${decision.reason}`)
}

// 4. Execute with cognitive support
const cognitive = new CognitiveArchitecture(db, llmRouter)
const reasoning = await cognitive.reason(tenantId, agentId, task, {
  memories,
  governance: decision
})

// 5. Execute skill
const result = await skillExecutor.execute(skillId, reasoning)

// 6. Evaluate and learn
const evaluation = await cognitive.evaluateReasoning(result, task)

await worldModel.recordExperience(tenantId, {
  agent_id: agentId,
  task_type: task.type,
  input_summary: task.description,
  outcome: result.status,
  outcome_score: evaluation.score,
  learnings: evaluation.insights
})

await learning.recordExperience(tenantId, experience)

// Periodic learning review (run hourly/daily)

const learning = new LearningAdaptationEngine(db, llmRouter)

// 1. Get insights from recent experiences
const insights = await learning.getInsights(tenantId, agentId)

console.log('Performance Trends:')
console.log(`  Average Success: ${insights.avg_outcome.toFixed(2)}`)
console.log(`  Total Experiences: ${insights.experience_count}`)
console.log(`  Common Patterns: ${insights.pattern_count}`)

// 2. Identify patterns
const patterns = await learning.identifyPatternInsights(tenantId, agentId, {
  min_frequency: 3,
  min_confidence: 0.7
})

for (const pattern of patterns) {
  console.log(`\nPattern: ${pattern.type}`)
  console.log(`  Description: ${pattern.description}`)
  console.log(`  Frequency: ${pattern.frequency}`)
  console.log(`  Impact: ${pattern.impact}`)
}

// 3. Generate adaptations
const adaptations = await learning.generateAdaptations(tenantId, agentId)

console.log(`\nGenerated ${adaptations.length} adaptations:`)

for (const adaptation of adaptations) {
  if (adaptation.validation_score > 0.8) {
    console.log(`  ✅ Applying: ${adaptation.description}`)
    await learning.applyAdaptation(tenantId, adaptation)
  }
  else {
    console.log(`  ⏸️  Queued: ${adaptation.description} (validation: ${adaptation.validation_score})`)
  }
}

// Background monitoring (run every 30 minutes)

const reasoning = new ReasoningEngine(db)

// Generate interventions
const interventions = await reasoning.generateInterventions(tenantId)

for (const intervention of interventions) {
  switch (intervention.type) {
    case 'URGENT':
      // Immediate notification
      await sendAlert({
        title: intervention.title,
        description: intervention.description,
        action: intervention.recommended_action,
        priority: 'high'
      })
      break

    case 'OPPORTUNITY':
      // Queue for team review
      await queueForReview({
        title: intervention.title,
        description: intervention.description,
        expected_impact: intervention.expected_impact,
        effort: intervention.estimated_effort
      })
      break

    case 'AUTOMATION':
      // Apply if high confidence
      if (intervention.confidence > 0.9) {
        await applyAutomation(intervention)
      }
      break
  }
}

// When handling a customer query

const crossSystem = new CrossSystemReasoning(tenantId)

// Get full customer context
const context = await crossSystem.query(
  `What do we know about customer ${customerEmail}?`
)

console.log('Customer Context:')
console.log(`  Name: ${context.entities.primary.name}`)
console.log(`  Tier: ${context.entities.primary.tier}`)
console.log(`  Recent Issues: ${context.issues.length}`)

// Check for recent interactions
const recentInteractions = await crossSystem.query(
  `What interactions have we had with ${customerEmail} in the past week?`
)

for (const interaction of recentInteractions.timeline) {
  console.log(`  ${interaction.date}: ${interaction.type} - ${interaction.summary}`)
}

// Check deal status if applicable
const deals = await crossSystem.query(
  `Are there any open deals for ${customerEmail}?`
)

if (deals.entities.deals.length > 0) {
  console.log(`\nOpen Deals: ${deals.entities.deals.length}`)
  for (const deal of deals.entities.deals) {
    console.log(`  ${deal.name}: $${deal.value} (${deal.stage})`)
  }
}

// 1. Initialization
const agent = await AgentService.getById(tenantId, agentId)
const context = await AgentContextResolver.resolve(tenantId, agentId, taskId)

// 2. Pre-execution Governance Check
const governance = new AgentGovernanceService(db)
const decision = await governance.canPerformAction(tenantId, agentId, action.type)

if (!decision.allowed) {
  return { error: `Action not allowed: ${decision.reason}` }
}

// 3. Memory Recall
const worldModel = new WorldModelService(db)
const memories = await worldModel.recallExperiences(
  tenantId,
  agent.role,
  task.description,
  5
)

// 4. Cognitive Processing
const cognitive = new CognitiveArchitecture(db, llmRouter)
await cognitive.initializeAgent(tenantId, agentId)

const reasoning = await cognitive.reason(
  tenantId,
  agentId,
  task,
  {
    memories: memories,
    constraints: decision.constraints,
    available_actions: decision.permitted_actions
  }
)

// 5. Skill Execution
const skill = await SkillRegistry.get(reasoning.selected_skill)
const result = await SkillExecutor.execute(skill.id, reasoning.parameters)

// 6. Cross-System Enrichment (if needed)
if (task.requires_context) {
  const crossSystem = new CrossSystemReasoning(tenantId)
  const enrichment = await crossSystem.query(
    `Context for ${task.description}`
  )
  result.enriched_context = enrichment
}

// 7. Result Evaluation
const evaluation = await cognitive.evaluateReasoning(result, task)

// 8. Experience Recording
await worldModel.recordExperience(tenantId, {
  agent_id: agentId,
  agent_role: agent.role,
  task_type: task.type,
  task_description: task.description,
  input_summary: JSON.stringify(task),
  outcome: result.status,
  outcome_score: evaluation.score,
  learnings: evaluation.insights,
  metadata: {
    reasoning_path: reasoning.path,
    skill_used: reasoning.selected_skill
  }
})

// 9. Learning Update
const learning = new LearningAdaptationEngine(db, llmRouter)
await learning.recordExperience(tenantId, {
  id: generateId(),
  type: result.success ? 'success' : 'failure',
  context: {
    tenantId,
    agentId,
    environment: 'production',
    conditions: { task_type: task.type }
  },
  inputs: task,
  actions: result.actions,
  outcomes: {
    primary: evaluation.score,
    secondary: evaluation.metrics,
    duration: result.duration,
    quality: evaluation.quality,
    efficiency: evaluation.efficiency
  },
  feedback: {
    immediate: result.user_feedback || 0,
    source: 'system',
    confidence: evaluation.confidence
  },
  reflections: [],
  patterns: [],
  timestamp: new Date()
})

// 10. Adaptation Check (async)
if (Math.random() < 0.1) {  // 10% chance to trigger adaptation
  const adaptations = await learning.generateAdaptations(tenantId, agentId)

  for (const adaptation of adaptations) {
    if (adaptation.validation_score > 0.9) {
      await learning.applyAdaptation(tenantId, adaptation)
    }
  }
}

return result

// 1. Rate Limiting
const abuseProtection = new AbuseProtectionService(db, tenantService, redis)
const withinLimit = await abuseProtection.checkRateLimit(tenantId)

if (!withinLimit) {
  throw new RateLimitError('Agent execution limit exceeded')
}

// 2. Resource Constraints
const maxExecutionTime = 300000  // 5 minutes
const maxMemoryUsage = 512  // MB
const maxTokens = 10000

// 3. Approval Workflow
if (riskLevel === 'HIGH') {
  const approval = await requestHumanApproval({
    agent_id: agentId,
    action: actionType,
    parameters: sanitized,
    reason: `High risk action: ${actionType}`,
    timeout: 60000  // 1 minute
  })

  if (!approval.granted) {
    throw new ForbiddenError('Action not approved')
  }
}

// 4. Audit Logging
await governance.logAction({
  tenant_id: tenantId,
  agent_id: agentId,
  action_type: actionType,
  allowed: true,
  maturity_level: agent.maturity_level,
  risk_level: riskLevel,
  timestamp: new Date(),
  parameters_hash: hash(sanitized),
  result_status: result.status,
  duration_ms: result.duration
})

// Cache governance decisions (short TTL)
const governanceCache = new NodeCache({ stdTTL: 60 })  // 1 minute

const cacheKey = `${tenantId}:${agentId}:${actionType}`
let decision = governanceCache.get(cacheKey)

if (!decision) {
  decision = await governance.canPerformAction(tenantId, agentId, actionType)
  governanceCache.set(cacheKey, decision)
}

// Cache recalled experiences (medium TTL)
const memoryCache = new NodeCache({ stdTTL: 300 })  // 5 minutes

const memoriesKey = `${tenantId}:${agentRole}:${hash(taskDescription)}`
let memories = memoryCache.get(memoriesKey)

if (!memories) {
  memories = await worldModel.recallExperiences(tenantId, agentRole, taskDescription, 5)
  memoryCache.set(memoriesKey, memories)
}

// Fire-and-forget for non-critical operations
// Don't await these

// 1. Experience recording
worldModel.recordExperience(tenantId, experience)
  .catch(err => logger.error('Memory recording failed', err))

// 2. Learning updates
learning.recordExperience(tenantId, learningExperience)
  .catch(err => logger.error('Learning update failed', err))

// 3. Adaptation checks
learning.generateAdaptations(tenantId, agentId)
  .then(adaptations => {
    for (const a of adaptations) {
      if (a.validation_score > 0.9) {
        learning.applyAdaptation(tenantId, a)
          .catch(err => logger.error('Adaptation failed', err))
      }
    }
  })
  .catch(err => logger.error('Adaptation generation failed', err))